Copyright: Copyright ® 1996 Progress Software Corporation


 Getting Started With the CINEWS Control

Related Topics

This topic introduces the Network News Transfer Protocol (NNTP) and the Crescent Internet ToolPak News control (CINEWS). You can access the following information:

What NNTP is

What the CINEWS control is

What CINEWS programming tasks are

The programming tasks topics identifies each task that CINEWS supports; they list the properties to set and the methods to call, and illustrate the tasks with code sample.


 What is NNTP?

Related Topics

NNTP stands for Network News Transfer Protocol. NNTP is a standard that defines how to post and retrieve messages called articles. Articles are simply messages grouped by topics, called newsgroups. Articles are stored on a server. Clients who want to retrieve articles must query the server. The NNTP standard defines the commands and responses that enable clients to retrieve and post articles. The NNTP standard is defined by RFC 977.


 What is the CINEWS Control?

Related Topics

The Crescent Internet ToolPak NNTP (CINEWS control) lets Visual Basic programmers build customized Usenet news client applications. It supports the standard NNTP commands that let you retrieve articles and newsgroup lists. In addition, it also supports the NNTP protocols commands that enable you to post articles to News servers.

CINEWS has a simple programming interface in which you set property values and call methods to perform the desired tasks. The methods (which generally do not take arguments) instead take the necessary data directly from the property sheet, and submit the request to the server. When the server returns its response, the control parses the data and updates the appropriate properties or populates a ListBox. You can simply read the data from a property value or a ListBox object.


 Programming Tasks

Related Topics

The CINEWS control lets you build NNTP client applications. Each client application must contain code that connects to an NNTP server before it can issue any requests to the News server. The connection requirements include:

1. Setting the HostName or HostAddress property and the NNTPPort property.

2. Calling the ConnectToNNTPServer method.

The code looks like this:

CINEWS1.HostName = NewsHost
CINEWS1.NNTPPORT = 119
nResult% = CINEWS1.ConnectToNNTPServer

You are connected when the NNTPServerConnection event fires. When the connection attempt succeeds, nResult% is an integer that represents the socket number opened by the ConnectToNNTPServer method. In addition, when the ConnectToNNTPServer succeeds, the NNTPServerConnection event fires.When the connection attempt fails, nResul%t is 0 and the WSAError event fires.

Once connected, you can perform these tasks with CINEWS:

Retrieve a list of newsgroups.

Find out how many articles are in a newsgroup.

Find out what newsgroups are available on the news server after a specified date and time.

Retrieve a List of New Articles

Retrieve an article.

Post an article.


  Retrieve a List of Newsgroups

Related Topics

1. Set these properties, then connect to the NNTP server:
HostName(or HostAddress)
NNTPPort (if other than the default)
NewsGroupListBoxName
ParseIncomingData
ListGroupNamesOnly

2. Call the LIST method in the NNTPServerConnection event module.

The code looks like this:

Form_Load
CINEWS1.HostName = NewsHost
CINEWS1.NNTPPort = 119
Set CINEWS1.NewsGroupListBoxName = ListBoxName
CINEWS1.ParseIncomingData =  True
CINEWS1.ListGroupNamesOnly = True.
CINEWS1.ConnectToNNTPServer

CINEWS1_NNTPServerConnection()
CINEWS1.LIST


 Find Out How Many Articles Are in Newsgroup

Related Topics

1. Set these properties, then connect to the NNTP Server.
HostName(or HostAddress) property
NNTPPort
NewsGroup

2. Call the GROUP method in the NNTPServerConnection event module.

3. The data can be read from these properties:
TotalArticles
FirstArticle
LastArticle

The code looks like this:

Form_Load
CINEWS1.HostName = NewsServerName
CINEWS1.NNTPPort = 119
CINEWS1.NewsGroup = comp.lang.basic.visual.misc
CINEWS1.ConnectToNNTPServer

CINEWS1_NNTPServerConnection()
CINEWS1.GROUP


 Find Out the New Newsgroups after a Specified Date and Time

Related Topics

1. Set these properties and call the ConnectToNNTPServer method:
HostName(or HostAddress) property
NNTPPort
Date
Time
NewsGroupListBoxName
ParseIncomingData
ListGroupNamesOnly

2. Call the NEWGROUPS method in the NNTPServerConnection module.

The code looks like this:

Form_Load
CINEWS1.HostName = NewsServerName
CINEWS1.NNTPPort = 119
CINEWS1.DATE = 951212
CINEWS1.TIME = 150000
Set CINEWS1.NewsGroupListBoxName = ListBoxName
CINEWS1.ParseIncomingData =  True
CINEWS1.ListGroupNamesOnly = True
CINEWS1.ConnectToNNTPServer

CINEWS1_NNTPServerConnection()
CINEWS1.NEWGROUPS


 Retrieve a List of New Articles

Related Topics

1. Set these properties, then connect to the NNTP server:
HostName(or HostAddress) property
NNTPPort
Date
Time
NewsGroup
ArticleListBoxName
ParseIncomingData
ListGroupNamesOnly

2. Call the NEWNEWS method in the NNTPServerConnection event module.

The code looks like this:

Form_Load
CINEWS1.HostName = NewsServerName
CINEWS1.NNTPPort = 119
CINEWS1.Date = 951212
CINEWS1.Time = 150000
CINEWS1.Set CINEWS1.NewsGroupListBoxName = ListBoxName
CINEWS1.ParseIncomingData =  True
CINEWS1.ListGroupNamesOnly = True
CINEWS1.ConnectToNNTPServer

CINEWS1_NNTPServerConnection()
CINEWS1.NEWNEWS


 Retrieve an Article

Related Topics

Call the  method to determine the number of the article that you want to retrieve.

1. Set these properties, then connect to the NNTP server:
HostName(or HostAddress) property
NNTPPort
ArticleNumber
NewsGroup

2. Call the ARTICLE method in the NNTPServerConnection event module.

3. You can read the data from these properties:
ArticleBody
ArticleHeader

NOTE  	If ArticleNumber is blank, the NNTP server returns the current article. Check the ArticleNumber or MessageID fields to determine the current article.

The code looks like this:

Form_Load
CINEWS1.HostName = NewsServerName
CINEWS1.NNTPPort = 119
CINEWS1.NewsGroup = NewsGroupName
CINEWS1.ArticleNumber = 2005
CINEWS1.ConnectToNNTPServer

CINEWS1_NNTPServerConnection()
CINEWS1.ARTICLE

Once the ArticleReceived event fires, you can check the ArticleHeader and ArticleBody properties for data.


 Post an Article to a News Server

Related Topics

1. Set these properties, then connect to the NNTP server:
HostName(or HostAddress) property
NNTPPort
Time

2. Call the POST method when the NNTPServerConnection event fires.

The code looks like this:

Form_Load
CINEWS1.HostName = NewsServerName
CINEWS1.NNTPPort = 119
CINEWS1.Time = 150000
CINEWS1.ConnectToNNTPServer

CINEWS1_NNTPServerConnection()
CINEWS1.POST

NOTE  	Some news servers do not allow you to POST articles. When news server do not support POSTs, they return a code of 440 immediately upon connection. If a news server accepts postings, but rejects a specific POST attempt, it returns code 441 and a line of text describing the reason the it rejected the POST.


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server


What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Retrieve a List of New Articles
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve an Article
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Post an Article to a News Server
The Crescent Internet ToolPak News Control Reference


Getting Started With the CINEWS Control
What is NNTP?
What is the CINEWS Control?
Programming Tasks
Retrieve a List of Newsgroups
Find Out How Many Articles Are in Newsgroup
Find Out the New Newsgroups after a Specified Date and Time
Retrieve a List of New Articles
Retrieve an Article
The Crescent Internet ToolPak News Control Reference


 The Crescent Internet ToolPak News Control

Related Topics

Control File

CINEWS.OCX

Object Type

CINEWS

Purpose

The Crescent Internet ToolPak Network News Transfer Protocol (CINEWS) control enables you to build customized Network News applications such as:

Retrieve articles and information about articles from a News server

Retrieve newsgroup lists and information about newsgroups from a News server

Post articles to a News server

The CINEWS control complies with the Network News Transfer Protocol standards defined in RFC 977.

Properties

About	ArticleBody c	ArticleHeader c
ArticleListBoxName c	ArticleNumber c	Container
Date c	Distributions c	Drag
DragIcon	DragMode	EventState c
FirstArticle c	Height	HostAddress c
HostName c	Index	LastArticle c
Left	ListGroupNamesOnly c	LocalFileName c
MessageID c	MethodState c	Name
NewsGroupListBoxName c	NewsGroup c	NNTPPort c
Object	Parent	ParseIncomingData c
ShowWhatsThis	Tag	Time c
Top	TotalArticles c	TotalGroups c
Visible	WhatsThisHelpID	Width
Events

ArticleReceived c	DragDrop	DragOver
EventStateChanged c	FileClosed c	GroupInformationReceived c
ListBoxesPopulated c	MethodStateChanged c	NNTPServerConnectionClosed c
NNTPServerConnection c	PacketReceivedc	PacketSent c
SocketClosed c	WSAError c
Methods

ARTICLE c	BODY c	CleanupConnection c
ConnectToNNTPServer c	GROUPc	HEADc
LAST c	LIST c	Move
NEWGROUPS c	NEWNEWS c	NEXT c
POST c	QUIT c	SLAVE c
STAT c	ZOrder
c A custom or modified property, method, or event.


ArticleBody Property

Applies To

CINEWS

Purpose

The ArticleBody property returns the body of the Article retrieved from the News server. It also set the text of the article to be posted to a News server.

Syntax

[Form.]CINEWS.ArticleBody[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime.

Comments

The ArticleBody property is updated by the ARTICLE or the BODY method when you retrieve an article from a News server. Set the ArticleBody (and ArticleHeader) property before calling the POST method.

See Also

ARTICLE, ArticleHeader, ArticleReceived, BODY, POST


ArticleHeader Property

Applies To

CINEWS

Purpose

The ArticleHeader property returns the header of the Article retrieved from the News server. It also set the text of the article to be posted to a News server.

Syntax

[Form.]CINEWS.ArticleHeader[ = String$]

Data Type

String

Usage

Read/Write at runtime and design time.

Comments

The ArticleHeader property is updated by the ARTICLE or HEAD method when you retrieve an article from a News server. Set the ArticleHeader (and ArticleBody property before calling the POST method.

See Also

ARTICLE, ArticleBody, ArticleReceived, HEAD, POST


ArticleListBoxName Property

Applies To

CINEWS

Purpose

The ArticleListBox Name property sets the name of the listbox that is bound to the CINEWS control. When the control retrieves a list of articles from a News server, it populates the listbox with the list.

Syntax

Set [Form.]CINEWS.ArticleListBoxName = ObjectName

Data Type

Object

Usage

Read/Write at runtime

Comments

The NEWNEWS method fills the ArticleListBox object. After the NewsGroupListBox or the ArticleListBox objects are filled, the ListBoxesPopulated event fires.

See Also

ListBoxesPopulated, NEWNEWS, NewsGroupListBoxName


ArticleNumber Property

Applies To

CINEWS

Purpose

The ArticleNumber property sets the number of the article that you want to retrieve from a News server.

Syntax

[Form.]CINEWS.ArticleNumber[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

Once you know the number of the article that you want to retrieve, set the ArticleNumber property and call the ARTICLE method to retrieve it. The News server assigns each article a number that is unique within a newsgroup.

To find out the list articles and their numbers, use the GROUP method to retrieve the articles for a specified newsgroup. You can first retrieve the list of articles available from a newsgroup, decide what article(s) you want to download, then invoke ARTICLE to retrieve the specific article by ArticleNumber or MessageID.

See Also

ARTICLE, ArticleListBoxName, ArticleReceived, GROUP, MessageID


Date Property

Applies To

CINEWS

Purpose

The Date property sets or returns the date that is used to query the News server about new newsgroups and new articles.

Syntax

[Form.]CINEWS.Date[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

The date must be in YYMMDD format. Where:

Format	Description
YY	The last two digits of the year.
MM	The two digits of the month - you must supply a leading zero when necessary.
DD	The day of the month - you must supply a leading zero when necessary.
The Date and Time properties are used by the NEWGROUPS and NEWNEWS methods.

NOTE  	The NEWGROUPS method queries the server for groups that are new since the specified date, and the NEWNEWS method queries the server for new articles posted to a newsgroup since the specified date.

See Also

ArticleListBoxName, NEWGROUPS, NEWNEWS, NewsGroupListBoxName, NewsGroup, Time


Distributions Property

Applies To

CINEWS

Purpose

The Distributions property sets a value that the News server must compare with the newsgroup distribution name. The News server returns only the newsgroups whose distribution name matches. Use Distributions to limit the newsgroups that end users can access.

Syntax

[Form.]CINEWS.Distributions[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

Set the Distributions property (optional) before calling the NEWGROUPS method.

See Also

NEWGROUPS


EventState Property

Applies To

CINEWS

Purpose

The EventState property returns the method currently in progress.

Syntax

[Integer%] = [Form.]CINEWS.EventState

Data Type

Integer

Usage

Read/Write at runtime

Comments

CINEWS updates EventState when an event fires. When the EventState property changes, CINEWS fires the EventStateChanged event.

The valid EventState property values are listed in the following table and are also in the CITPAK.BAS file.

This event...	has this constant...	with this integer value...
ListBoxesPopulated	CINEWS_LBPOP	130
NNTPServerConnection	CINEWS_CONN	131
SocketClosed	CINEWS_SCLOSED	132
NNTPServerConnectionClosed	CINEWS_CONN	133
FileClosed	CINEWS_FCLOSED	134
ArticleReceived	CINEWS_ARECEIVED	135
You can test the EventState to initiate an action or control program flow.

See Also

EventStateChanged


FirstArticle Property

Applies To

CINEWS

Purpose

The FirstArticle property returns the number of the first article in a specified newsgroup.

Syntax

[Long&] = [Form.]CINEWS.FirstArticle

Data Type

Long

Usage

Read/Write at runtime

Comments

FirstArticle is updated by the GROUP method. GROUP also updates the LastArticle and TotalArticles properties. You can use FirstArticle, LastArticle and TotalArticles to determine the set of articles available for the newsgroup since a given date and time. The GroupInformationReceived event fires when the FirstArticle, LastArticle, and TotalArticles properties are updated.

See Also

GROUP, GroupInformationReceived, LastArticle, TotalArticles


HostAddress Property

Applies To

CINEWS

Purpose

The HostAddress property sets the IP address of the News server.

Syntax

[Form.]CINEWS.HostAddress[ = String$]

Data Type

String

Usage

Read/Write at design time

Comments

The HostAddress identifies the host to the network (the Internet). HostAddress consists of the network number and the local host number. You must use either the HostName or the HostAddress to retrieve lists or articles from a News server.

An example of an IP address is:

198.137.64.1

NOTE  	You must use either the HostName or the HostAddress property to connect to a News server. When you provide both, CINEWS uses HostName.

Set HostAddress or HostName before calling the ConnectToNNTPServer method.

See Also

ConnectToNNTPServer, HostName


HostName Property

Applies To

CINEWS

Purpose

The HostName property sets the DNS name of the News server.

Syntax

[Form.]CINEWS.HostName[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

The HostName is the name that identifies an NNTP server to the Internet. Depending on your connection to the Internet, the HostName might contain simply a machine name like crescentserver, or it can be a fully qualified Internet name that follows this format: machine.organizationname.com. Contact your site administrator to determine the correct format to supply.

Set HostAddress or HostName before calling the ConnectToNNTPServer method.

NOTE  	You must use either the HostName or the HostAddress property to connect to a News server. When you provide both, CINEWS uses HostName.

See Also

ConnectToNNTPServer, HostAddress


LastArticle Property

Applies To

CINEWS

Purpose

The LastArticle property returns the number of the last article in a specified newsgroup.

Syntax

[Long&] = [Form.]CINEWS.LastArticle

Data Type

Long

Usage

Read/Write at runtime

Comments

LastArticle is updated by the GROUP method. GROUP also updates the FirstArticle and TotalArticles properties. This information can be used to determine the set of articles available for the newsgroup since a given date and time. GroupInformationReceived event fires when the FirstArticle, LastArticle, and TotalArticles properties are updated.

See Also

FirstArticle, GROUP, GroupInformationReceived, TotalArticles


ListGroupNamesOnly Property

Applies To

CINEWS

Purpose

The ListGroupNamesOnly property lets you narrow the contents of the NewsGroupListBox object to include only the names of newsgroups.

Syntax

[Form.]CINEWS.HostName[ = Boolean%]

Data Type

Boolean Integer

Usage

Read/Write at design time and runtime

Comments

The ListGroupNamesOnly property supports these values:

Value	Description
True	The NewsGroupListBox displays the names of the newsgroups only.
False	The NewsGroupListBox displays the names of the newsgroups and the numbers of the first and last articles in the group.
See Also

LIST, NewsGroupListBoxName


LocalFileName Property

Applies To

CINEWS

Purpose

The LocalFileName property sets the path and the name of a file on the client (local machine) where the News file is written when it is retrieved.

Syntax

[Form.]CINEWS.LocalFileName[=String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

The ARTICLE and LIST methods update the LocalFile. Data is appended to the end of the file. Note that because data is appended to the end of this file, it can grow quite large.

See Also

ARTICLE, LIST


MessageID Property

Applies To

CINEWS

Purpose

The MessageID property sets the MessageID of the article that you want to retrieve from a News server.

Syntax

[Form.]CINEWS.MessageID[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

Once you know the number of the article that you want to retrieve, set the MessageID or the ArticleNumber property and use the ARTICLE method to retrieve it. The News server assigns each article a number and a MessageID that are unique within a newsgroup.

To find out the set of articles for a newsgroup, including each articles ArticleNumber or MessageID, use the GROUP method. Once youve retrieved the list of articles available from a newsgroup, and decided what article(s) you want to download, invoke ARTICLE to retrieve the specific article by its number or its MessageID.

If you specify both an ArticleNumber and a MessageID, CINEWS uses the MessageID value.

See Also

ARTICLE, ArticleNumber, ArticleReceived


MethodState Property

Applies To

CINEWS

Purpose

The MethodState property returns the method currently in progress.

Syntax

[Integer%] = [Form.]CINEWS.MethodState

Data Type

Integer

Usage

Read/Write at runtime

Comments

CINEWS updates MethodState when you call a method like ARTICLE, BODY, or HEAD. When the MethodState property changes, CINEWS fires the MethodStateChanged event.

The valid MethodState property values are listed in the following table and are also in the CITPAK.BAS file.

This method...	has this constant...	with this integer value...
ARTICLE	CINEWS_ARTICLE	35
BODY	CINEWS_BODY	47
GROUP	CINEWS_GROUP	36
HEAD	CINEWS_HEAD	46
LAST	CINEWS_LAST	38
LIST	CINEWS_LIST	39
NEWGROUPS	CINEWS_NEWGROUPS	40
NEWNEWS	CINEWS_NEWNEWS	41
NEXT	CINEWS_NEXT	42
POST	CINEWS_POST	43
QUIT	CINEWS_QUIT	44
SLAVE	CINEWS_SLAVE	45
STAT	CINEWS_STAT	37
You can test the MethodState to initiate an action or control program flow.

See Also

MethodStateChanged


NewsGroup Property

Applies To

CINEWS

Purpose

The NewsGroup property sets the name of the newsgroup from which you want to retrieve articles or listings of articles

Syntax

[Form.]CINEWS.NewsGroup[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

The GROUP or NEWNEWS methods pass NewsGroup to the News server.

You can find names of valid newsgroups by invoking the LIST method and viewing the returned list in the NewsGroupListBox object.

See Also

GROUP, NEWNEWS, NewsGroupListBoxName


NewsGroupListBoxName Property

Applies To

CINEWS

Purpose

The NewsGroupListBoxName property sets the name of the listbox object that is bound to the CINEWS control. When the control retrieves news group names from a News server, the listbox is automatically filled with the list of news groups.

Syntax

[Form.]CINEWS.NewsGroupListBoxName = ObjectName

Data Type

Object

Usage

Read only at runtime

Comments

The LIST method fills the NewsGroupListBox object. After the NewsGroupListBox or the ArticleListBox objects are filled, the ListBoxesPopulated event fires.

See Also

ArticleListBoxName, ListBoxesPopulated, LIST


NNTPPort Property

Applies To

CINEWS

Purpose

The NNTPPort property sets or returns the port number used for NNTP communications.

Syntax

[Form.]CINEWS.NNTPPort

Data Type

Integer

Usage

Read/Write at design time and runtime

Comments

The default NNTP port number is 119. This property is required along with the HostAddress or HostName property before you can initiate a connection to a News server with the ConnectToNNTPServer method.

You can find out the NNTP port number for your site by contacting your system administrator, or using the bGetServiceByName method provided by the TCP/IP control.

See Also

HostAddress, HostName, ConnectToNNTPServer


ParseIncomingData Property

Applies To

CINEWS

Purpose

The ParseIncomingData property sets whether to parse data and place it in a listbox.

Syntax

[Form.]CINEWS.ParseIncomingData[ = Boolean%]

Data Type

Boolean Integer

Usage

Read/Write at design time and runtime

Comments

ParseIncomingData has these values:

Value	Behavior
True	CINEWS parses the data and uses it to fill the ArticleListBox or the NewsGroupListBox.
False	CINEWS does not parse the data and does not populate the listboxes.
See Also

ArticleListBoxName, NewsGroupListBoxName


Time Property

Applies To

CINEWS

Purpose

The Time property sets the time that is used to query the News server about new newsgroups and new articles.

Syntax

[Form.]CINEWS.Time[ = String$]

Data Type

String

Usage

Read/Write at design time and runtime

Comments

Time must be in HHMMSS format. Where

Format	Description
HH	hours on the 24-hour clock
MM	minutes from 00-59
SS	seconds from 00-59
The News server assumes that the time refers to the servers time zone. You can also specify GMT, which sets the date and time to Greenwich Mean Time.

The Date and Time properties are used by the NEWGROUPS and NEWNEWS methods. The NEWGROUPS method queries the server for groups that are new since the specified date, and the NEWNEWS method queries the server for new articles posted to a newsgroup since the specified date.

See Also

ArticleListBoxName, Date, NEWGROUPS, NEWNEWS, NewsGroupListBoxName, NewsGroup


TotalArticles Property

Applies To

CINEWS

Purpose

The TotalArticles property returns the total number of articles currently available for a newsgroup.

Syntax

[Form.]CINEWS.TotalArticles[ = Integer%]

Data Type

Integer

Usage

Read/Write at runtime

Comments

The TotalArticles property is updated by the GROUP method. GROUP also updates the FirstArticle and LastArticle properties. This information can be used to determine the set of articles available for the newsgroup since a given date and time. GroupInformationReceived event fires when the FirstArticle, LastArticle, and TotalArticles properties are updated.

See Also

FirstArticle, GROUP, GroupInformationReceived, LastArticle


TotalGroups Property

Applies To

CINEWS

Purpose

The TotalGroups property returns the number of groups available on the connected News server.

Syntax

[Form.]CINEWS.TotalGroups[ = Integer%]

Data Type

Integer

Usage

Read/Write at runtime

Comments

This property is updated by the LIST method.

See Also

LIST, NewsGroupListBoxName, TotalArticles


ArticleReceived Event

Applies To

CINEWS

Purpose

The ArticleReceived event fires when the ArticleBody and the ArticleHeader properties have been updated.

Syntax

CINEWS_ArticleReceived()

Comments

The following table lists the methods that populate the ArticleHeader and ArticleBody properties:

This method...	populates this property...
ARTICLE	ArticleBody, ArticleHeader
BODY	ArticleBody
HEAD	ArticleHeader
See Also

ArticleBody , ArticleHeader


EventStateChanged Event

Applies To

CINEWS

Purpose

The EventStateChanged event fires when the value of the EventState property changes.

Syntax

Sub CINEWS_EventStateChanged(ByVal state As Integer)

Comments

The EventState property identifies the method that was most recently called. You can test the EventState property to determine a state change and thus initiate an action, or control program flow. The values of state are identified in the listed in the following table and are also in the CITPAK.BAS file.

This event...	has this constant...	with this integer value...
ListBoxesPopulated	CINEWS_LBPOP	130
NNTPServerConnection	CINEWS_CONN	131
SocketClosed	CINEWS_SCLOSED	132
NNTPServerConnectionClosed	CINEWS_CONN	133
FileClosed	CINEWS_FCLOSED	134
ArticleReceived	CINEWS_ARECEIVED	135
You can test the EventState to initiate an action or control program flow.

See Also

EventState


FileClosed Event

Applies To

CINEWS

Purpose

The FileClosed event fires when the file stream from the server has ended.

Syntax

Sub CINEWS_FileClosed()

Comments

The FileClosed event indicates that communications with the News server has terminated, and that all data has been retrieved and parsed.

See Also

LocalFileName


GroupInformationReceived Event

Applies To

CINEWS

Purpose

The GroupInformationReceived event fires when the FirstArticle, LastArticle, and TotalArticles properties are updated.

Syntax

Sub CINEWS1_GroupInformationReceived()

See Also

FirstArticle, GROUP, LastArticle, TotalArticles


ListBoxesPopulated Event

Applies To

CINEWS

Purpose

The ListBoxesPopulated event fires when the ArticleListBox and NewsGroupListBox objects have been filled.

Syntax

Sub CINEWS_ListBoxesPopulated()

Comments

The NEWNEWS method fills the ArticleListBox object. The LIST method fills the NewsGroupListBox object.

See Also

ArticleListBoxName, LIST, NEWNEWS, NewsGroupListBoxName


MethodStateChanged Event

Applies To

CINEWS

Purpose

The MethodStateChanged event fires when the value of the MethodState property changes.

Syntax

Sub CINEWS_MethodStateChanged(ByVal state As Integer)

Comments

The MethodState property identifies the method that was most recently called. You can test the MethodState property to determine a state change and thus initiate an action, or control program flow. The values of state are identified in the listed in the following table and are also in the CITPAK.BAS file.

This method...	has this constant...	with this integer value...
ARTICLE	CINEWS_ARTICLE	35
BODY	CINEWS_BODY	47
GROUP	CINEWS_GROUP	36
HEAD	CINEWS_HEAD	46
LAST	CINEWS_LAST	38
LIST	CINEWS_LIST	39
NEWGROUPS	CINEWS_NEWGROUPS	40
NEWNEWS	CINEWS_NEWNEWS	41
NEXT	CINEWS_NEXT	42
POST	CINEWS_POST	43
QUIT	CINEWS_QUIT	44
SLAVE	CINEWS_SLAVE	45
STAT	CINEWS_STAT	37
See Also

MethodState


NNTPServerConnection Event

Applies To

CINEWS

Purpose

The NNTPServerConnection event fires when a connection to a News server is established.

Syntax

Sub CINEWS_NNTPServerConnection()

Comments

Once the NNTPServerConnection event fires your application can start to interact with the News server by invoking the ARTICLE, GROUP, HEAD, LIST, NEWGROUPS, NEWNEWS , POST, SLAVE, or STAT method.

Because the NNTPServerConnection event fires when a connection is established, the NNTPServerConnection_Event module is a good module in which to place any initial code.

See Also

ARTICLE, GROUP, HEAD, LIST, NEWGROUPS, NEWNEWS, NNTPServerConnectionClosed, POST, SLAVE, STAT


NNTPServerConnectionClosed Event

Applies To

CINEWS

Purpose

The NNTPServerConnectionClosed event fires when a connection to a News server terminates.

Syntax

Sub CINEWS_NNTPServerConnectionClosed()

Comments

Connections are terminated at the request of the News server.

See Also

NNTPServerConnection


PacketReceived Event

Applies To

CINEWS

Purpose

The PacketReceived event fires when the CINEWS receives a packet from the connected News server.

Syntax

Sub CINEWS_PacketReceived(ByVal Packet As String, ByVal bytes_in As Integer)

Comments

The packet is the actual data received from the server. The packet might contain an article, a list of newsgroups, or other data depending on the method used to obtain the packet. The bytes_in value is the number of bytes in the current packet.

See Also

PacketSent


PacketSent Event

Applies To

CINEWS

Purpose

The PacketSent event fires when the control sends a packet to the News server.

Syntax

Sub CINEWS_PacketSent(ByVal bytes_out As Integer)

Comments

The value of bytes_out is the number of bytes in the current packet. Packets are sent in response to the all of the methods except CleanupConnection.

See Also

PacketReceived


SocketClosed Event

Applies To

CINEWS

Purpose

The SocketClosed event fires when the socket closes.

Syntax

Sub CINEWS_SocketClosed()

Comments

The socket should remain open during program execution. If the SocketClosed event fires while your application is running, an error condition has occurred.

See Also

CleanupConnection


WSAError Event

Applies To

CINEWS

Purpose

The WSAError event fires when CINEWS receives a WINSOCK error.

Syntax

Sub CINEWS_WSAError(ByVal error_number As Integer)

Comments

Use the WSAError event to monitor the Winsock activity. The error_number identifies the Winsock error that occurred. These errors are listed in the CITPAK.BAS file.

See Also

CITPAK.BAS


ARTICLE Method

Applies To

CINEWS

Purpose

The ARTICLE method returns a specific article including the body and the header.

Syntax

CINEWS.ARTICLE

Data Type

None

Comments

Set the ArticleNumber (or the MessageID) and the NewsGroup properties before invoking ARTICLE. If you do not set the ArticleNumber (or the MessageID), the News server returns the current article. The current article is the article at which the News servers cursor is located. Check the ArticleNumber or MessageID properties to determine the current message. When you supply both ArticleNumber and MessageID, ARTICLE uses MessageID. If you want to retrieve the current ARTICLE clear both the ArticleNumber and the MessageID properties.

ARTICLE updates the ArticleBody and ArticleHeader properties.

You can use the GROUP method to determine the number of the article that you want to retrieve. If you want to retrieve just the article header, use the HEAD method. If you want to retrieve just the article body, use the BODY method.

See Also

ArticleBody, ArticleHeader, ArticleListBoxName, ArticleNumber, ArticleReceived, GROUP, MessageID


BODY Method

Applies To

CINEWS

Purpose

The BODY method returns the body of a specific article.

Syntax

CINEWS.BODY

Data Type

None

Comments

Set the NewsGroup property before invoking the BODY method.

The News server returns the body of the current article. The current article is the article at which the News servers cursor is located. Check the ArticleNumber or MessageID properties to determine the current message.

The BODY method updates the ArticleBody property.

You can use the GROUP method to determine the number of the article that you want to retrieve. If you want to retrieve just the article header, use the HEAD method. If you want to retrieve both the article body and the article header, use the ARTICLE method.

See Also

ArticleBody, ArticleHeader, ArticleListBoxName, ArticleNumber, GROUP, HEAD


CleanupConnection Method

Applies To

CINEWS

Purpose

The CleanupConnection method closes the socket and cleans up WINSOCK.

Syntax

CINEWS.CleanupConnection

Data Type

None

Comments

By default CINEWS opens the socket when you invoke the ConnectToNNTPServer method and closes it when you issue the QUIT method. The CleanupConnection method fires the SocketClosed event.

Use CleanupConnection to clear errors that might occur when a method fails, or in other cases where the socket does not close properly and you need to restart the connection process.

NOTE  	This method is only used when all else fails.

See Also

ConnectToNNTPServer, QUIT, SocketClosed, WSAError


ConnectToNNTPServer Method

Applies To

CINEWS

Purpose

The ConnectToNNTPServer method establishes a connection to a News server

Syntax

nResult = CINEWS.ConnectToNNTPServer

Data Type

Integer

Comments

You must establish a connection to the News server before CINEWS can retrieve or post articles. To establish a connection you must set the HostName or HostAddress and the NNTPPort properties. When the connection attempt succeeds, nResult is an integer that represents the socket number opened by the ConnectToNNTPServer method. The return of a socket number does not indicate successful connection; the NNTPServerConnection event fires when the connection attempts succeeds. When the connection attempt fails, nResult is 0 and the WSAError event fires.

See Also

HostAddress, HostName, NNTPPort, NNTPServerConnection, WSAError


GROUP Method

Applies To

CINEWS

Purpose

The GROUP method returns the number of the first article, the number of the last article and the total number of articles available for a specified newsgroup.

Syntax

CINEWS.GROUP

Data Type

Integer

Comments

Set the NewsGroup property before invoking the GROUP method. The GROUP method updates the properties as described in the following table.

This article data ...	can be read from this property...
The number of the first article	FirstArticle
The number of the last article	LastArticle
The total number of articles	TotalArticles
The GroupInformationReceived event fires when the FirstArticle, LastArticle and TotalArticles properties are updated.

See Also

FirstArticle, GroupInformationReceived, LastArticle, NewsGroup, TotalArticles


HEAD Method

Applies To

CINEWS

Purpose

The HEAD method returns the header for the current article.

Syntax

CINEWS.HEAD

Data Type

None

Comments

The current article is the one where the News server cursor is presently located. Check the ArticleNumber or MessageID properties to determine the current message.

The HEAD method updates the ArticleHeader property.

You can use the GROUP method to determine the number of the article that you want to retrieve. If you want to retrieve just the article body, use the BODY method. If you want to retrieve both the article body and the article header, use the ARTICLE method.

See Also

ArticleBody, ArticleHeader, ArticleListBoxName, ArticleNumber, BODY, GROUP


LAST Method

Applies To

CINEWS

Purpose

The LAST method repositions the News servers cursor to the article preceding the current article.

Syntax

CINEWS.LAST

Data Type

None

Comments

Set the NewsGroup property before calling the LAST method. The current article is the one at which the News servers cursor is presently located. Read the ArticleNumber or MessageID properties to determine the current message.

The LAST method updates the ArticleNumber property with the number of the new current article.

You can use the NEXT method to reposition the cursor to the article following the current article.

See Also

ArticleNumber, LastArticle, FirstArticle, NewsGroup


LIST Method

Applies To

CINEWS

Purpose

The LIST method requests a list of newsgroups from a News server.

Syntax

CINEWS.LIST

Data Type

None

Comments

If you want the list of newsgroups automatically displayed in ListBox format, set the NewsGroupListBoxName property before calling the LIST method

The LIST method updates the NewsGroupListBox object (if specified). When the ListBox object is populated, the ListBoxesPopulated event fires.

Because the number of newsgroups might be quite large, this method might take awhile to retrieve the requested information. Once youve retrieved this information, it is recommended that you invoke the NEWGROUPS method when you want to update your list of newsgroups.

See Also

FileClosed, ListBoxesPopulated, NEWGROUPS, NewsGroupListBoxName


NEWGROUPS Method

Applies To

CINEWS

Purpose

The NEWGROUPS method returns the names of the newsgroups that have been created since a specified date and time.

Syntax

CINEWS.NEWGROUPS

Data Type

Integer

Comments

Set the Date, Time, and NewsGroupListBoxName (optional) properties before calling the NEWGROUPS method.

The NEWGROUPS method populates the NewsGroupListBox object (if set). If you set the NewsGroupListBoxName property and the NEWGROUPS method succeeds, the ListBoxesPopulated event fires after the NewsGroupListBox object is filled.

See Also

Date, ListBoxesPopulated , NewsGroupListBoxName, Time


NEWNEWS Method

Applies To

CINEWS

Purpose

The NEWNEWS method returns a list of the articles posted to a newsgroup since a specified date and time.

Syntax

CINEWS.NEWNEWS

Data Type

Integer

Comments

Set the Date, Time,NewsGroup and ArticleListBoxName (optional) before calling NEWNEWS. The NEWNEWS method updates the ArticleListBox object (if set). If you set the ArticleListBoxName property and the NEWNEWS method succeeds, the ListBoxesPopulated event fires after the ArticleListBox object is filled.

See Also

ArticleListBoxName, Date, ListBoxesPopulated, NewsGroup, Time


NEXT Method

Applies To

CINEWS

Purpose

The NEXT method advances the News servers cursor to the next article.

Syntax

CINEWS.NEXT

Data Type

None

Comments

If the current article is the last article, the NEXT method fails.

See Also

LAST


POST Method

Applies To

CINEWS

Purpose

The POST method lets you add new articles to a newsgroup.

Syntax

CINEWS.POST

Data Type

None

Comments

Set the ArticleBody and ArticleHeader properties before calling the POST method. Note that some servers do not allow new postings. The server returns a response code (to the PacketReceived event) if posting is not allowed.

See Also

WSAError


QUIT Method

Applies To

CINEWS

Purpose

The QUIT method terminates the connection to the News server.

Syntax

CINEWS.QUIT

Data Type

Integer

See Also

ConnectToNNTPServer


SLAVE Method

Applies To

CINEWS

Purpose

The SLAVE method notifies a News server that you are a slave server, not an individual user.

Syntax

CINEWS.SLAVE

Data Type

None

Comments

Most (but not all) News servers give requests from slave servers higher priority.


STAT Method

Applies To

CINEWS

Purpose

The STAT method lets you move the News server cursor to a specific article.

Syntax

CINEWS.STAT

Data Type

None

Comments

Set the ArticleNumber (or MessageID) and the NewsGroup properties before calling the STAT method. STAT does not return an article to the to the local machine. It simply moves the News server cursor to the specified article.

See Also

ARTICLE, BODY, HEAD


 General Tab

Applies To

CINEWS

This custom tab lets you set these custom properties:

NNTP Server Configuration properties:

HostName	HostAddress	NNTPPort
Article Related properties:

ArticleNumber	MessageID


 Sound Events Tab

Applies To

CINEWS

This custom tab lets you assign sounds via .WAV files to custom events. The following table lists the hidden properties that define the sound object and the event to which they are applied:

Event	Hidden Property
FileClosed	FileClosedWAV
NNTPServerConnection	NNTPServerConnectionWAV
NNTPServerConnectionClosed	NNTPServerConnectionClosedWAV
ListBoxesPopulated	ListBoxesPopulatedWAV
PacketReceived	PacketReceivedWAV
PacketSent	PacketSentWAV
SocketClosed	SocketClosedWAV
WSAError	WSAErrorWAV
You can set the sound associations at design time or runtime. You can test the sounds from within the property page. At runtime, an event is fired and a sound is played asynchronously where an association is made.

To associate a sound, you can type in the full qualified path for any events you want to associate or click the Browse... button and select it from the dialog box. After you enter a sound, you can click the test button to hear it. If the sound file is invalid or missing you will hear nothing when you click Test.